Sound Manager 3.2 contains some new routines for determining sound formats and converting between sound formats. This document describes the application programming interface to these new features and the bug fixes.
Determining Sound Hardware Settings
New Sound Manager routines: GetSoundOutputInfo() and SetSoundOutputInfo().
Two routines have been added to get and set information about the sound environment: GetSoundOutputInfo() and SetSoundOutputInfo. Both routines use a selector-based interface similar to the SPBGetDeviceInfo/SPBSetDeviceInfo routines found in the Sound Input Manager, and in fact they use the same selectors.
GetSoundOutputInfo() and SetSoundOutputInfo() operate directly on a sound output device, and can be used to retrieve and change information about the hardware settings. These routines should be used instead of attempting to communicate directly with sound output components. Setting the output device parameter to nil causes the default output device to be used. These calls are similar to GetSndInfo() and SetSndInfo() but do not require an opened sound channel.
These new calls are only available with Sound Manager version 3.1 or later. Check for this by calling SndSoundManagerVersion() for the installed version.
For example, to determine the sampling rate of the sound hardware on the default output device, you could use this code:
unsigned long *numFrames, unsigned long *dataOffset)
ParseAIFFHeader returns information describing the audio data in the given AIFF file. The fRefNum parameter specifies the open AIFF file to use. The sndInfo parameter is a SoundComponentData structure that returns the following information about the format of the sound in the AIFF file:
flags - always returns 0
format - the sound format (i.e. 'raw ', 'twos', 'MAC3', etc.)
numChannels - the number of channels (i.e. 1 = mono, 2 = stereo)
sampleRate - the sampling rate (in samples/second)
sampleCount - the number of audio samples in the file
buffer - always returns 0
reserved - always returns 0
The numFrames parameter returns the number of frames of audio data in the file, and the dataOffset parameter returns the byte offset of the first audio sample in the file.
Errors:
siInvalidCompression - compression type not supported
badFileFormat - file does not contain valid AIFF data
unsigned long *numFrames, unsigned long *dataOffset)
ParseSndHeader returns information describing the audio data in the given 'snd ' resource handle. The sndHandle parameter specifies the sound handle to use. The sndInfo parameter is a SoundComponentData structure that returns the following information about the format of the sound in the handle:
flags - always returns 0
format - the sound format (i.e. 'raw ', 'twos', 'MAC3', etc.)
numChannels - the number of channels (i.e. 1 = mono, 2 = stereo)
sampleRate - the sampling rate (in samples/second)
sampleCount - the number of audio samples in the handle
buffer - always returns 0
reserved - always returns 0
The numFrames parameter returns the number of frames of audio data in the handle, and the dataOffset parameter returns the byte offset of the first audio sample in the handle.
Errors:
siInvalidCompression - compression type not supported
badFormat - file does not contain valid 'snd ' data
GetCompressionName returns a string describing the given compression format in a string that can be displayed to the user. The compressionType parameter specifies the compression format, and the name is returned in compressionName. This string can be used in pop-up menus and other user interface elements to allow the user to select a compression format.
Errors:
memFullErr - not enough memory to load name
siInvalidCompression - compression type not supported
resNotFound - compression name not available
Converting Sounds
An architecture has been added to Sound Manager 3.2 to allow you to easily convert between sound formats. Some of the operations that can be performed are compression, decompression, channel conversion, sample rate conversion and sample format conversion.
A conversion session is begun by calling SoundConverterOpen, to which you pass the format of the sound to be converted and the resulting output format. A SoundConverter identifier is returned that must be passed to all further routines in this session. SoundConverterClose is used to close the session.
SoundConverterGetBufferSizes allows you to determine input and output buffer sizes based on a target buffer size. This lets you create buffers to fit the conversion established with SoundConverterOpen.
Converting a sound is a three-step process. First, you call SoundConverterBeginConversion to initiate the conversion and reset the SoundConverter to default settings. Then SoundConverterConvertBuffer is called one or more times to convert sequential buffers of the input data to the output format. Finally, when all input data has been converted, SoundConverterEndConversion flushes out any data left in the converter.
SoundConverterOpen sets up the conversion session and returns a SoundConverter identifier to be passed to all further routines. The inputFormat parameter specifies the format of the sound data to be converted using a SoundComponentData structure. The following fields must be set up to describe the sound correctly:
flags - set to 0
format - the sound format (i.e. 'raw ', 'twos', 'MAC3', etc.)
numChannels - the number of channels (i.e. 1 = mono, 2 = stereo)
sampleRate - the sampling rate (in samples/second)
sampleCount - set to 0
buffer - set to 0
reserved - set to 0
The outputFormat parameter specifies the output format, and must be passed fields similar to inputFormat. Output fields that are different from input fields will cause a conversion. For example, if the input sound format is 'raw ' and the output format is 'MAC3', the data resulting from the conversion will be compressed with MACE 3:1. This allows any combination of compression, decompression, channel conversion, sample size conversion and sampling rate conversion. A SoundConverter identifier is returned to manage the session, which must be passed to all further routines.
This routine cannot be called at interrupt time.
Errors:
memFullErr - not enough memory
siInvalidCompression - compression type not supported
SoundConverterClose terminates the session and frees up all memory and services associated with this session.
This routine cannot be called at interrupt time.
Errors:
none
pascal OSErr SoundConverterGetBufferSizes(SoundConverter sc, unsigned long targetBytes,
unsigned long *inputFrames, unsigned long *inputBytes,
unsigned long *outputBytes)
SoundConverterGetBufferSizes is used to determine the input and output buffer sizes for a given target size. This is so you can make sure your buffers will fit the conversion parameters established with SoundConverterOpen.
The targetBytes parameter is the approximate number of bytes you would like both your input and output buffers to be. The inputFrames and inputBytes parameters return the actual size you should make your input buffer, in frames and bytes respectively. The outputBytes parameter returns the size in bytes for your output buffer.
Note: The returned input and output buffer sizes CAN be larger than your target size settings. This is because they are rounded up depending on the format, but they will be very close to the target settings. Also note that the input and output sizes may be very different, depending on the input and output formats given in SoundConverterOpen. The sizes are calculated assuming you will convert all data in the input buffer to the output buffer.
This routine cannot be called at interrupt time.
Errors:
notEnoughBufferSpace - input bytes target too small
unsigned long *outputFrames, unsigned long *outputBytes)
SoundConverterConvertBuffer converts a buffer of data from the input format to the output format. The inputPtr parameter points to the input data, and inputFrames gives the number of frames in that buffer. The outputPtr parameter specifies where the output data should be placed. The output Frames and outputBytes parameters return the number of frames and bytes placed in the output buffer respectively.
This routine will consume all the data in the input buffer, but, depending on the complexity of the conversion, not all the converted data may be put in the output buffer right away. The SoundConverterEndConversion routine is used to flush out all this remaining data before a conversion session is closed.
If you are using this routine in conjunction with SoundConverterGetBufferSizes, it is very important that you do not pass in a value in inputFrames larger than the frames value returned by SoundConverterGetBufferSizes, or you will overflow your output buffer. The SoundConverterConvertBuffer calls converts ALL the input data!
unsigned long *outputFrames, unsigned long *outputBytes)
SoundConverterEndConversion ends a conversion. Any data remaining in the converters is flushed out and returned here.
This routine can be called at interrupt time.
Errors:
none
Conversion Example
The following is an example of how to use the sound conversion architecture to convert a buffer of silence to IMA 4:1, changing the sampling rate in the process.
New version of InstallMoveHHiPatch that will install on PowerMacs when the old Memory Manager is running. On PowerMacs with our new native PowerPC sound components we use more than 3k of the stack. The MoveHHi() in the new ROMs will only preserve 3k so we have to patch it to preserve more stack space.
Use a nil sound output component reference to specify the default device when calling Get/SetSoundOutputInfo().
Deal with left over samples during compression better by preserving them across calls to PlaySourceBuffer(). This allows sequential calls to a compressor with non-packet multiple buffer sizes to seam together without clicks.
Fixed SetSource() in the format converter so it does not ask the source for 8-bit twos-complement data, which no other sound component supports. This fixes problems when the format converter is installed after the mixer and is asked to output 8-bit twos.
In the sample rate converter the samplesToSkip field now stores the amount to skip into a new buffer. The byteOffset field is updated to this value when a new buffer is received. This fixes a problem playing scales with the freqDuration command when a new buffer is played before the old buffer has reached the end.
The gestaltSoundAttr proc being installed needs to avoid using unknown CPUs or re-cycled machine types.
Sound Input
siSetupCDAudio
This selector is only used by input devices that have special requirements in order to hear the audio from the CD player. For example, currently the 840AV and PowerMacs require the user to open the Sound control panel, select the Inputs panel, and then open the Options dialog. From here they have to select the CD Input and also check the Play-Through option. The new siSetupCDAudio avoids this troublesome operation by setting up the input device to allow you to hear audio CDs from the audio CD player.
The infoData parameter points to a short word. A value of 1 means to setup the hardware (e.g. set input source to CD and turn on Play-Through). A value of 0 means to return the input hardware to some initial state, either the default settings or the settings prior to setting up for the CD audio. Any other value is an error. If the input device had no special needs for CD audio (e.g. the audio is heard regardless of the input hardware settings) then the selector is not supported and it returns an error. The SPBGetDeviceInfo() should return a 1 or 0 value depending on its current setting. If the input source is the CD and Play-Through, if required, is on, then return the value of 1. This should happen even if nothing ever requested setting up for CD audio. It should return the state of the actual condition of the input hardware.
Multiply bytesPerSample by 8 to get sampleSize for sound header. Fixes bug in SetupSndHeader with arbitrary compression formats.
Hardware
siHardwareVolume
This output selector was previously defined, but should be documented and implemented as returning the volume of the device that can be heard. For example, the PowerMac can have the speaker and the headphones both be audible to the user. In this case, return the loudest volume setting. If both the speaker and the headphones are muted, then again return the loudest setting. If one is muted and the other is audible, then return the volume of the audible source.
siHardwareMute
This output selector was previously defined, but should be documented and implemented as returning the mute state of all sources that can be heard. For example, the PowerMac has a speaker and headphone source. If no headphones are plugged in, then return the mute state of the speakers. If headphones are inserted, then return the mute state of both (e.g. siHardwareMute is muted when both speakers and headphones are muted). The idea is if the user has sources that can be heard and all are muted, then the hardware has been muted. If any one of the sources can be heard, then the hardware is not muted.
siHardwareBusy
Used by all input and output devices. This returns the state of the hardware. Typically, this means whether or not the hardware interrupts are active. For input devices, the infoData parameter points to a short word. For output devices, the infoPtr is a short word containing the value. A value of 0 represents that the hardware is not busy, whereas 1 represents busy. This selector is only supported by the get calls, since it doesn't make since to "set" a device busy.
Fixed the siHardwareBusy selector in the 8500 series.
Added speaker and headphone muting into the preferences. This allows for the user to specify the speaker is no muted when using external speakers or headphones, and the next time the machine is started the user's preference is restore. Previously it would default to always muting the speaker if something was inserted into the headphone jack.
Preserve register A0 within DetermineInputSource() when calling GetInitialPreferences().
Interfaces
SndSoundManagerVersion(), SPBVersion(), and MACEVersion() should all return a NumVersion. A recent version of the interfaces were changed to return an unsigned long, but this fails with creating native PowerPC code.
A new version of SoundLib has been released to include all of the new Sound Manager 3.2 API.
